TA Unit Design Guide

Last updated:  12/20/98 22:01

The outline used below was modelled after the information I found at the TAORF (Total Annihilation Orbital Research Facility) web site tutorial.  The example unit I've used in my illustrations are the files associated with TADD's Core Hellfire unit.  If you read down the contents of this page in order, it should serve as a good step-by-step guide to unit design.

You can vote on my site as one of the "Annihilated Top 200" web sites by clicking on the image to the right.

When a unit is created, all of the files and information associated with that unit are stored and compressed within a UFO file.   Within the UFO file is a directory structure similar to the image seen here to the right.    (See the Nuts and Bolts page for a brief description of these files, and a description of the directories and files that are contained within them).

In general, when creating a unit, all of the directories seen in this image are of importance.  However, if your newly created unit makes use of existing sounds and weapons, then you will not need the "sounds" and "weapons" directories.

So, the first step you will take in the creation of your unit is to simple create a subdirectory somewhere on your hard drive and give it the "short" name of the unit you are going to create.  (For example, the "ARM Advanced Construction Sub" has a short name of "ARMACSUB".  Within this subdirectory, create the directory structure you see in the illustration above.  The unit's short name's (or "abbreviation") first 3 letters almost always (except in the case of a few 3rd party units) tell which side the unit is made by - either ARM or COR. And the total length of the unit abbrieviation is 8 letters.

When designing a unit, don't be shy to beg, borrow, and steal whatever you may need - a lot of the details of how units are built came from simply searching the existing HPI files and comparing the differences between the different units.  In addition, why go through the bother of making a 3D model of a gun flare or laser turret when there are already so many units that already have them!  When in doubt, look at something that already exists that is similar to your own unit for comparison and contrast.  The important thing is to plan in advance and test the unit like crazy when (you think) it's done.

Note:  The sketch shown was for my first experimental unit, the ARM Sphere.  It was scrapped shortly after the prototype phase.  I just through the sketch was kind of cool, so I put it here.

Within the units subdirectory you created, you will create a text file with a name of unitname.fbi, where "unitname" is the short name of your unit.    Any text editor, such as Windows' Notepad or Wordpad works sufficiently.   The FBI file contains the majority of the properties of your unit, such as whether or not it can move, fly, nanolathe, etc.

When creating your FBI file, it is probably a good idea to find some existing unit that is somewhat similar to the one you are creating, and copy and modify that FBI file.  See the FBI File Content Description page for more detailed information on the format of this file, and the different variables and values that can be set.

Some key pieces of information within this file are:

A 3rd party utility called FRED can be downloaded to assist you in the editing of your FBI files.  It can be downloaded from TAMMO's download area.

The TDF files are much simpler than the FBI, because all of the strings in them are always the same.   The file contains one or several similar blocks of information that describe what construction units can build your unit, which menu build page your unit appears on for that construction unit, and which of the 6 buttons on that particular page does your unit appear on.  Your new unit must occupy a position in some unit's build menu(s), but must not appear in the same position as any other unit.  To help ensure there are no conflicts between your unit and any existing TADD or CaveDog unit, see the ARM or CORE TADD Build Menus list I've created.

Create your unitname.tdf file in your download directory (where "unitname" is the short name of your unit), and use your favorite text editor according to the format described in the TDF Download page.

A  tool is now available called TDFEdit98 (available from...that's right...TADD) that will simplify the creation of this file for you by prompting you for the required values.

Probably the most difficult part of creating a new unit is, as you would expect, creating the 3D model that represents what your unit will look like.  It is precisely because of this difficulty that CaveDog cannot and will not release any sort of Unit Editor similar to the way they released TAE for map editing.

In actuality, you will be creating two 3D objects in this step.  The first object is the unit itself.   The second object is the "corpse".  That is, it's the shape and texture of the debris that is left behind when your unit dies.  Each of these objects will be placed in the objects3d subdirectory for your unit and will be named unitname.3do and unitname_dead.3do, respectively, where "unitname" is the short name for your unit.

You will need at least two tools (and probably 3) to create your 3DO files:

I can't say much more about using any of these tools because of the complexity involved.  Again, the best bet is to try the tools and use them to import, export, and create DXF and 3DO files, and experiment with some of the existing units to see how they were all developed.  See also the 3DO File Content Description page for a little more information.

(9/10/98)  I have added an additional web page titled Rhino/TA Editing Tips to give a few additional tips for using Rhino to do your 3D modelling.

When working with 3DOBuilder and Rhino (or whatever 3D rendering program you are using), a new "tool" is availabe to help you create and use the groundplate.   Groundplates.zip (available from TADD) contains unit groundplates of several sizes to help you ensure that your unit is the correct size.

Once you have created the 3D model of your unit, it is time to describe how it is animated.  Animation includes things like how the unit recoils when it fires, how does it aim its guns, how does it activate and deactivate, and so on.

Although this is probably the second most difficult part of creating a unit, it is well within the scope of most computer-literate people.   In the scripts subdirectory for your unit, create a file with the name unitname.bos, where "unitname" is the short name of your unit.  The BOS file is a text file that somewhat resembles a C programming language source file.  It contains variable definitions, constant definitions, and subroutine definitions.  For a full description of the syntax of the BOS file, see the BOS File Content Description page.

When your BOS file is complete, a 3rd party utility called Cobbler can be downloaded.   This tool will "compile" your BOS file "source code" into the final COB file.  The resulting COB file will be placed in the same scripts subdirectory where your BOS file is.  It can be downloaded from TADD's download area.

Note:  You don't have to include the BOS file if you don't want to in your final unit if you feel that you want to keep the contents of your BOS file a secret.

A WAV file is a WAV file as far as I know.  There are a million tools out there to capture sounds and create the WAV file.  In the end, you will take whatever sound files you wish to use that are unique to your unit, and place them in the sounds subdirectory for your unit.  You can name the WAV files anything you wish as long as they have the WAV extension (you will be calling out these file names if and when you create your unit-unique weapon later on in the process.  

This step in the unit creation process is optional, since you can make use of any of the other sounds that are already included in Total Annihilation.

In Total Annihilation, a "feature" is any object within a game that is neither directly a part of the map, nor a unit.  Some examples of features are trees, rocks, metal deposits, thermal vents, and the "corpses" left behind when a unit is destroyed.  The look of the corpse was defined in the earlier step of defining your 3D objects.  This file is also where you will define the "heap" that is left behind when your unit has suffered so much damage that there is nothing but a small (or large) pile of rubble left behind.

Describing the properties of the corpse of your unit is similar to the step in which you defined the properties of the unit with the FBI file under the units subdirectory.   However, with TA features, they are defined by a TDF file in the features/corpses subdirectory. 

Create a file in the features/corpses subdirectory with a name of unitname_dead.tdf, where "unitname" is the short name of your unit.  In this file, you will describe properties such as how much metal can be reclaimed from the wreckage, how high it is, whether or not it can be reclaimed, and what the reclamation animation looks like.    Details of the features TDF file can be found in the TDF Features web page.

A new tool is now available called TDFEdit98 (available from...that's right...TADD) that will simplify the creation of this file for you by prompting you for the required values.

When creating a unit, you will most likely want to arm it with some sort of weapon.  (duh!)  You can make use of any of the 200+ units that are already available in Total Annihilation and the expansion units, or you can create your own weapons!

Weapons are described in a TDF file in the weapons subdirectory.  If you wish to create a weapon of your own, create a file in the weapons subdirectory with a name of unitname_weapons.tdf, where "unitname" is the short name of your unit.  (Note: you don't really need to name this file in this way, but it's nice if everybody follows a consistent naming convention for everything).     Details of the weapon TDF file can be found in the TDF Weapons web page.

Within the weapon's TDF file, you will describe the properties of the weapon in terms of what type it is (ballistic, beam, or missile), how much damage it does, what it looks like, whether or not it can catch trees on fire, and so on.  It's actually very surprising how many different weapon properties are available!  If you create a new weapon of your own, you may also want to create a special animation for your weapon to display when the weapon hits its target.  You will do this in the Animation step below.

A utility exists to help in the creation of a weapon TDF file called Total Weapon.   It can be downloaded from TADD's download area. 

One important note:  Just as units themselves have a Unit ID assigned to them that must be unique, so also do the weapons.  The big down-side is that Total Annihilation has a hard limit of 255 weapons available for use, and CaveDog used over 200 of them with their units alone.  The remaining weapon ID's are therefore scarce, and it could be difficult to ensure that a weapon ID you choose will be unique between CaveDog and many of the other groups on the Internet who are creating weapons of their own.

The first picture of your unit you need is a picture that is displayed on the screen when you hit F1 with a unit selected during a game.  This is the picture that is shown along with the other unit information.  Essentially, this is a simple 96x96 pixel PCX-format image of your unit, typically placed on a nifty-looking background.

To create your PCX file, use any of a number of graphical editing tools, such as Paint Shop Pro, Windows Paint, etc.  When you are finished creating your picture (whether it be a BMP, GIF, or PCX file), save the file as a PCX file.  The image is saved in a PCX file in the unitpics subdirectory, and is given the short name of your unit as the filename.  Kinboat's 3DOBuilder will create a BMP file of the appropriate size automatically for you, but you'll have to use some software like Paint Shop Pro to convert it to PCX format.

A group of background images is availabe for you to download and use.  It is called Buildpics, and can be found (among other places) at TADD's download web site. 

Rather than embarassing yourself with a free-hand stick-figure drawing, you could use the modified Unit Viewer that comes with Kinboat's 3DOBuilder application (again, see TADD's download area), and cut-and-paste along with your background picture to create your final PCX image.

There are two types of "animations" you may want to create for your unit.  The first is required, and the second is optional.

The first "animation" you want to create is simply a collection of 3 images of your unit that will be used as the images in the build menus for the construction units that will build your unit.  This file will be given a name of unitname_GADGET.gaf, where "unitname" is the short name of your unit, and will be placed in the anims subdirectory.  (It is referred to as a "gadget", because that is essentially what these become - the button "gadget" on the screen).

The second (and possibly others) would be animations that you want to create for a new weapon that you might have created in the previous Weapons step.  This would be the small (or large) explosion animation that is shown when your weapon hits its target.   This file can be given whatever name is used in the "explosiongaf" portion (or whichever type of explosion it models) of the weapon's TDF file descripton.

In each instance, the type of file you want to create is a GAF file.  A GAF file is a collection of bitmap images.   Each image within the collection can have a number of image frames, thus making an animation sequence. 

Details of the GAF file can be found in the GAF File Content Description web page.  A number of tools are available on the Internet to help in the creation and extraction of GAF files, including GAFeditor, Gaffer, GAF-Pro, and the extraction tool GAF 2 Texture.  For the 3-frame gadget GAF, however, Kinboat's 3DOBuilder can kindly create this one for you!!!

The easiest part of creating a unit is to simply create a text file that contains a human-readable description of what the unit is, what it does, what it costs, and why you would want to use it.  Although not required, it's good sportsmanship to do this for everyone else.

It is not necessary to create this file as part of your UFO file, but it is a handy place to store the file.

A text file with an extension of TXT is created with any simple text editor, such as Windows' Notepad or Wordpad.  It should be placed in a directory within the UFO file with the name of doc or docs.   (Note:  in this example, the directory name of "doc" was used, but "docs" is probably the preferred method).

When all is said and done, and you're ready to pack everything together into one file, it's time to create the UFO file.  Your weapon of choice is HPIPack, which you can download from TADD.  When creating your UFO file, you can include any other files that you want to include, as long as the required files are all present in the proper subdirectories within it.  (For example, the Core Hellfire UFO file also contains a DXF file that was probably used during unit creation).

When ZIPping your final UFO file to be distributed to your friends (and enemies!), the UFO file should be shipped along with a separate copy of the TXT description file from the docs directory.  This file should be copied into the C:\CAVEDOG\TOTALA\DOCS directory (or wherever their Total Annihilation was installed) as part of your installation procedure as a simple courtesy to remind users what your unit is and what it does.